Doc de la lib construite pour explorer PORTIC

Objectif de cette lib :

Voir la doc de l'API PORTIC : https://gitlab.huma-num.fr/portic/porticapi/-/tree/master/porticapi]
Voir le code de l'API toflit18 : https://github.com/medialab/toflit18)

Sommaire des fonctions proposées :

Fonctions principales (résultats directement utilisables pour l'étude) :

Portic:

Toflit :

Fonctions secondaires (résultats qui vont plutôt aider à paramétrer les fonctions principales, nourrir des fonctions de visualisation, ...)

Utils :

Portic:

Toflit :

Principe généraux d'utilisation du client

Les fonctions Portic et Toflit sont appelées respectivement depuis portic_client et toflit_client. Les fonctions utils sont appelables directement.

Si des paramètres spécifiques peuvent être utilisés, ils sont décrit dans la doc spécifique à chaque fonction.

Imports et bootstrapping des clients

Méthodes pour l'accès à PORTIC

pouvant être appelées depuis portic_client

portic_client.get_pointcalls(params)

Synopsis:


Paramètres de requête spécifiques :

nom type valeurs défault description
start_year <int/string> année de début
end_year <int/string> année de fin
year <int/string> année exacte (l'emporte sur début/fin)

Exemple : je veux tous les pointcalls enregistrés dans le Poitou en 1789

portic_client.get_fieldnames()

Synopsis: Récupère les noms des variables des données et leur description (très pratique quand on ne sait plus ce qu'une colonne signifie)

regarder attributs name et description

Exemple : je veux tous les noms de colonnes présents dans les données navigo

portic_client.get_flows(params)

Synopsis:

Retourne une liste de flux, c'est-à-dire de voyages liés à des ports spécifiques, soit en y entrant (direction "in"), soit en en sortant (direction "out"), soit en ayant navigué autour (direction "in-out")


Paramètres de requête spécifiques :

nom type valeurs défault description
ports list(string) UHGS_id 4326 liste des ids de ports à filtrer (séparés par des virgules)

Exemple

portic_client.get_travels(params)

Synopsis:

Récupère les données de trajectoires calculées.

possibilité de filtrer à une valeur ou une liste de valeurs par attribut


Paramètres de requête spécifiques :

nom type valeurs défault description

Exemple : tous les voyages au départ d'un port rattaché à la direction des Fermes de La Rochelle, dont le port d'attache du navire est Dieppe et Noirmoutier, et son pavillon français, ...

portic_client.get_departures_details(params)

Synopsis:

Récupère tous les ports aux alentours d'un point géographique donné.


Paramètres de requête spécifiques :

nom type valeurs défault description
lon flottant (minLon,maxLon) ? longitude du centre de la zone à requêter
lat flottant (minLat,maxLat) ? latitude du centre de la zone à requêter
radius flottant (0,?) 100 ? rayon en kilomètres

Exemple : description

portic_client.get_destinations_aggregated(params)

Synopsis:

Retourne une aggrégation des amirautés de départ de voyages qui arrivent dans des points situés dans le voisinage (voir paramètre radius) du point requêté.

'label': amirauté de départ

'value': nombre de voyages partis de cette amirauté


Paramètres de requête spécifiques :

nom type valeurs défault description
lon flottant (minLon,maxLon) ? longitude du centre de la zone à requêter
lat flottant (minLat,maxLat) ? latitude du centre de la zone à requêter
radius flottant (0,?) 100 ? rayon en kilomètres

Exemple

portic_client.get_ports(params)

Synopsis: Retourne une liste de ports_points au format JSON


Paramètres de requête spécifiques :

nom type valeurs défault description
srid int --- --- identifiant de référence spatiale unique associé à un système de coordonnées, une tolérance et une résolution spécifiques

Exemple

Méthodes pour l'accès à TOFLIT

pouvant être appelées depuis toflit_client :

toflit_client.get_flows(start_year, end_year, year, params,**kwargs)

Synopsis : récupère les flux toflit18

Paramètres de requête spécifiques :

nom type valeurs défault description
start_year <int/string> None année de début
end_year <int/string> None année de fin
year <int/string> None année exacte (l'emporte sur fin/début)
params list toutes les colonnes propriétés à renvoyer
**kwargs <arr/string> valeurs à filtrer dans les flux (peut être une ou plusieurs valeurs)

toflit_client.get_customs_regions()

Synopsis :

Récupère toutes les customs region (direction des Fermes) de la base


Exemple

toflit_client.get_product_classifications(classification)

Synopsis :

Récupère les classifications de produits


Exemple

toflit_client.get_partner_classifications()

Synopsis :

Récupère les classifications de partenaires


Exemple

toflit_client.get_classification_groups(classification)

Synopsis :

Récupère l'ensemble des catégories associées à une classification en particulier (sans le détail des valeurs)


Exemple

toflit_client.get_classification_search(classification)

Synopsis :

Récupère le détail des groupements associés à une classification en particulier.


Paramètre d'URL classification : le nom de la classification préfixé par son type (ex. "product_simplification", ou "partner_source")


Exemple

toflit_client.get_locations(classification, params)

Synopsis :

Récupère le réseau des lieux (directions et partenaires) et le montant de leurs échanges


Paramètre classification : l'id de la classification de partenaire à utiliser


Paramètres de requête spécifiques :

nom type valeurs défault description
dateMin entier (années) ? année de début
dateMax entier (années) ? année de fin
kind string ('total', 'import', 'export') 'total' type de flux
sourceType string (types de source) ? id du type de source à utiliser
product liste d'objets (objects avec {{"id","name","value"}) None liste des produits à filtrer
productClassification string (ids de classification) None Classification de produit à utiliser pour le filtre

Exemple

toflit_client.get_flows_per_year(type, params)

Synopsis :

Récupère les flux par année par direction ou par type de source


Paramètre type : le type de flux 'direction' ou 'sourceType'


Paramètres de requête spécifiques :

nom type valeurs défault description
dateMin entier (années) ? année de début
dateMax entier (années) ? année de fin
kind string ('total', 'import', 'export') 'total' type de flux
sourceType string (types de source) ? id du type de source à utiliser
partner liste d'objets (objects avec {"name","id"}) None les partenaires commerciaux à prendre en compte (e.g. {name: 'Alsace', id: 'Alsace~partner_orthographic'})
partnerClassification string (ids de classification) None Classification de partenaire à utiliser pour le filtre
product liste d'objets (objects avec {{"id","name","value"}) None liste des produits à filtrer
productClassification string (ids de classification) None Classification de produit à utiliser pour le filtre
direction chaîne (noms de direction) '$all$' nom de la direction à filtrer

Exemple

toflit_client.get_time_series(params)

Synopsis :

Récupère des séries temporelles à propos des flux de marchandises


Paramètres de requête spécifiques :

nom type valeurs défault description
dateMin entier (années) ? année de début
dateMax entier (années) ? année de fin
kind string ('total', 'import', 'export') 'total' type de flux
sourceType string (types de source) ? id du type de source à utiliser
partner liste d'objets (objects avec {"name","id"}) None les partenaires commerciaux à prendre en compte (e.g. {name: 'Alsace', id: 'Alsace~partner_orthographic'})
partnerClassification string (ids de classification) None Classification de partenaire à utiliser pour le filtre
product liste d'objets (objects avec {{"id","name","value"}) None liste des produits à filtrer
productClassification string (ids de classification) None Classification de produit à utiliser pour le filtre
direction chaîne (noms de direction) '$all$' nom de la direction à filtrer

Exemple

toflit_client.get_product_terms(classification, params)

Synopsis :

Récupère des séries temporelles à propos des flux de marchandises


Paramètre classification : l'id de la classification de produit à utiliser


Paramètres de requête spécifiques :

nom type valeurs défault description
dateMin entier (années) ? année de début
dateMax entier (années) ? année de fin
kind string ('total', 'import', 'export') 'total' type de flux
sourceType string (types de source) ? id du type de source à utiliser
partner liste d'objets (objects avec {"name","id"}) None les partenaires commerciaux à prendre en compte (e.g. {name: 'Alsace', id: 'Alsace~partner_orthographic'})
partnerClassification string (ids de classification) None Classification de partenaire à utiliser pour le filtre
child liste d'objets (objects avec {{"id","name","value"}) None liste des produits à filtrer
childClassification string (ids de classification) None Classification de produit à utiliser pour le filtre
direction chaîne (noms de direction) '$all$' nom de la direction à filtrer

Exemple

toflit_client.get_sources_types()

Synopsis :

Récupère les types de sources disponibles


Exemple

Utils

nest_toflit18_flow(flow)

Synopsis: Cette fonction organise un flux toflit18 tel que reçu depuis les données en csv sous la forme d un ensemble de clés thématiques qui contiennent chacun les propriétés correspondantes.


Exemple :

nest_portic_pointcall(pointcall)

Synopsis: Cette fonction organise un pointcall portic tel que reçu depuis les données en csv sous la forme d un ensemble de clés thématiques qui contiennent chacun les propriétés correspondantes.


Exemple :

build_cooccurence_graph(data, key_1, key_2, **kwargs)

Synopsis : Cette fonction prend un ensemble de dict (data) et deux noms de clés présents dans chaque dict. Elle renvoie un graphe networkx de coocurrence entre les dicts.


Paramètres de requête spécifiques (**kwargs) :

nom type valeurs défault description
color_1 code rgb (string?) rgb(0, 255, 0) couleur des noeuds de type 1
color_2 code rgb (string?) rgb(255, 0, 0) couleur des noeuds de type 2
node_min_size int 1 taille min des noeuds
node_min_size int 10 taille max des noeuds

Exemple :

get_online_csv(url)

Synopsis: Cette fonction permet de récupérer le contenu d'un csv en ligne. Pour les google spreadsheets: fichier > publier sur le web > format csv > copier le lien.

Bien mettre l'url sous forme de string dans les params

get_pointcalls_commodity_purposes_as_toflit_product(pointcalls, product_classification)

Synopsis : Cette fonction prend en entrée une liste de pointcalls et un nom de classification de produits ("product_simplification" par défaut). Elle renvoie en sortie la liste des dict de pointcalls enrichis avec une propriété "commodity_purposes" qui ont les propriétés existantes de PORTIC pour commodity_purpose[2,3,4] + une propriété "commodity_as_toflit qui donne la valeur correspondante dans toflit18.

get_pointcalls_port_as_toflit_partner(pointcalls, partner_classification)

Synopsis : Cette fonction prend en entrée une liste de pointcalls et un nom de classification de partenaire ("partner_simplification" par défaut). Elle renvoie en sortie la liste des dict de pointcalls enrichis avec une propriété "pointcall_as_toflit_partner".

get_pointcalls_homeport_as_toflit_partner(pointcalls, partner_classification)

Synopsis : Cette fonction prend en entrée une liste de pointcalls et un nom de classification de partenaire ("partner_simplification" par défaut). Elle renvoie en sortie la liste des dict de pointcalls enrichis avec une propriété "homeport_as_toflit_partner".